6 The Format Description

The variable forms-format-list specifies the format of the data in the data file, and how to convert the data for display in Forms mode. Its value must be a list of Forms mode formatting elements, each of which can be a string, a number, a Lisp list, or a Lisp symbol that evaluates to one of those. The formatting elements are processed in the order they appear in the list.

string

A string formatting element is inserted in the forms “as is,” as text that the user cannot alter.

number

A number element selects a field of the record. The contents of this field are inserted in the display at this point. Field numbers count starting from 1 (one).

list

A formatting element that is a list specifies a function call. This function is called every time a record is displayed, and its result, which must be a string, is inserted in the display text. The function should do nothing but returning a string.

The function you call can access the fields of the record as a list in the variable forms-fields.

symbol

A symbol used as a formatting element should evaluate to a string, number, or list; the value is interpreted as a formatting element, as described above.

If a record does not contain the number of fields as specified in forms-number-of-fields, a warning message will be printed. Excess fields are ignored, missing fields are set to empty.

The control file which displays /etc/passwd file as demonstrated in the beginning of this manual might look as follows:

;; This demo visits /etc/passwd.

(setq forms-file "/etc/passwd")
(setq forms-number-of-fields 7)
(setq forms-read-only t)                 ; to make sure
(setq forms-field-sep ":")
;; Don’t allow multi-line fields.
(setq forms-multi-line nil)

(setq forms-format-list
      (list
       "====== /etc/passwd ======\n\n"
       "User : "    1
       "   Uid: "   3
       "   Gid: "   4
       "\n\n"
       "Name : "    5
       "\n\n"
       "Home : "    6
       "\n\n"
       "Shell: "    7
       "\n"))

When you construct the value of forms-format-list, you should usually either quote the whole value, like this,

(setq forms-format-list
     '(
       "====== " forms-file " ======\n\n"
       "User : "    1
       (make-string 20 ?-)
       …
      ))

or quote the elements which are lists, like this:

(setq forms-format-list
      (list
       "====== " forms-file " ======\n\n"
       "User : "    1
       '(make-string 20 ?-)
       …
      ))

Forms mode validates the contents of forms-format-list when you visit a database. If there are errors, processing is aborted with an error message which includes a descriptive text. See Error Messages, for a detailed list of error messages.

If no forms-format-list is specified, Forms mode will supply a default format list. This list contains the name of the file being visited, and a simple label for each field indicating the field number.